fix(service-storage)!: an upload link is refused at issue for a file field whose readonlyWhen holds now (#32768) - #33079

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/mcp, @objectstack/objectql, @objectstack/service-storage, touching 22 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/objectql/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

25 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json c4196099eee97f9fc48995063dde978fe5516a5d.

⛔ 8 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 3837bf7ffbe49e1c11df6ba421a61c2d621e4188 && git checkout 3837bf7ffbe49e1c11df6ba421a61c2d621e4188
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin c4196099eee97f9fc48995063dde978fe5516a5d 506782945fd54b00d5ea4e4f8717d1049c23d03c && git checkout -B drift-repro c4196099eee97f9fc48995063dde978fe5516a5d && git merge --no-ff 506782945fd54b00d5ea4e4f8717d1049c23d03c

node scripts/docs-audit/affected-docs.mjs --json c4196099eee97f9fc48995063dde978fe5516a5d

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs c4196099eee97f9fc48995063dde978fe5516a5d → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#8 · os-elon-musk · session_016WV4cwqTK71kjQzHae8T5J

Contract-review-claim: session_016WV4cwqTK71kjQzHae8T5J · head c3e09f3 · 2026-11-13T09:43Z

domain:server#8 · os-elon-musk · session_016WV4cwqTK71kjQzHae8T5J

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: c3e09f3499f39756036d4774816589bed4ee2333
Local-runs: none
Scope: .changeset/32768-upload-link-readonly-when-at-issue.md, packages/objectql/src/engine-field-write-lock.ts, packages/objectql/src/engine-field-write-lock.test.ts, packages/objectql/src/engine.ts, packages/objectql/src/index.ts, packages/objectql/src/readonly-strict-errors.ts, packages/services/service-storage/src/record-file-access.ts, packages/services/service-storage/src/record-file-access.integration.test.ts, packages/mcp/src/mcp-http-tools.ts, packages/qa/dogfood/test/showcase-mcp-record-files.dogfood.test.ts, content/docs/ai/connect-mcp.mdx + packages/objectql/src/engine-update.ts, packages/objectql/src/validation/rule-validator.ts, packages/objectql/src/engine-insert.ts, packages/objectql/src/engine-validate.ts, packages/runtime/src/domains/mcp.ts, packages/services/service-storage/src/file-attachment-service.ts, packages/services/service-storage/src/storage-service-plugin.ts, packages/mcp/src/skill-md.ts (cited code outside the diff, read, not reviewed)

Read at 2026-11-13T09:44Z: the diff against merge base 4079b06b, the live PR body, card #32768 with claim 6847540308, re-post 6847846915 and report 6849438419, and the head's check-runs. Narrowing face (no schema or governed path in the tree; Clause-②: yes (narrowing) on body and changeset).

① Derived judgments

• Check-runs on the head at read time: 16 completed success (among them Check Changeset, PR-body guards, Governed Surface Queue Guard, Spec property liveness, Type Check · source gates, Lint · docs & code guards); 19 still in progress (Test Core 1/8 to 8/8, Build Core, Build Docs, Type Check · workspace / consumer gates / debt ledger, five Lint families, Live E2E UI); none failed. This record does not stand in for the pending ones.
• The dogfood shards do not run on pull_request by workflow design, so the dogfood pin's evidence is the dev's local battery at d9c65672 (458 files, 3845 tests, exit 0). The one later commit touches only the objectql unit-test driver double; read in the diff, true.
• Report claims read against the code: no packages/spec path and no engine-validate.ts in the diff (true); file-content.ts untouched (true); the surface correction to service-storage is declared on re-post 6847846915 before the push (true).
• Ablation (report): removing the refusal line in record-file-access.ts fails exactly the new integration pin. The pin's shape agrees: it asserts code, status, the whole sentence and an unchanged open-link row count, all of which need the refusal.

② Semver level

• patch on @objectstack/objectql, @objectstack/service-storage, @objectstack/mcp: correct. Metadata-protocol: none is true (no key, value or metadata type moves), and a non-protocol change, widening or breaking, ships patch with its banner. The three packages are exactly the published ones the diff moves; the dogfood package and docs publish nothing.
• BREAKING banner present on the changeset and the PR body, with FROM, TO and the one-line fix; fix(...)!: title agrees.
• ADR-0087 marker not-required (no-migration-prescription) is present and its reason holds: no schema key or stored shape moves. Check Changeset, which runs the registration check, is green on this head.

③ Boundary flags

• Clause-②: yes (narrowing): correct arm. The tool issues less than it did. The accompanying widening (one public method ObjectQL#judgeFieldWriteLock, one type export FieldWriteLock from packages/objectql/src/index.ts) is declared in the changeset prose and the claim's declaration note; one arm per line, and narrowing is the governing one.
• readonlyDropReasonPhrase is exported from its module only, not from the package entry; true of index.ts.
• IDataEngine (spec) is not widened: service-storage reads the method as an optional member of its own RecordFileEngine interface. An engine without it is not asked and the consume-side strict write still refuses.
• engine.validate / ValidateDataResponse: not in the diff; the documented limit ("readonlyWhen is not run") does not move.
• Skills-docs: none holds: nothing under skills/** names create_upload_link. The tool description and connect-mcp.mdx carry the refusal.

④ Design judgment

• The judgement is the engine's own evaluation. judgeFieldWriteLock calls stripReadonlyWhenFields (the function engine-update.ts calls for the by-id update), with previous from readUpdatePriorRow and parent from resolveMasterDetailParent behind hasParentScopedReadonlyWhenInPayload, the update's own gate. No CEL is evaluated in service-storage or packages/mcp. With the payload carrying the stored value, record equals the stored row, so any predicate over other fields gets the verdict the upload's write gets. The two places it can differ from the write (beforeUpdate hooks not run; a predicate reading the incoming value of its own field) are named on the method. In both the consume-side strict write still judges, so the worst case is a link whose upload is refused (the old behaviour) or a refusal slightly early; never an attach past a lock.
• The narrowing makes an existing refusal real earlier; it takes no working capability away. FROM and TO are true of the code: before, the link was minted and the PUT answered 403 FIELD_NOT_ACCESSIBLE "Nothing was attached: ..."; now createUploadLinkAs refuses before store.createFile, so no link row is written.
• Complete over the doors: createUploadLinkAs has one implementation (RecordFileAccess), one delegate (FileAttachmentService) and one caller (packages/runtime/src/domains/mcp.ts, the MCP bridge). The REST routes under /storage/upload-links/:token only open and spend a link; no REST or SDK door mints one. The attachments target takes the field === undefined branch and is not judged; pinned by the integration test.
• Code and words: 403 FIELD_NOT_ACCESSIBLE, the code this door already answers for static readonly and for the same lock at consume time. The phrase is REASON_PHRASE.readonly_when read through the new accessor, not re-spelled. The dogfood pin ties it to the lock update_record reports on the same field (droppedFields, reason readonly_when).
• should-fix (docs wording, content/docs/ai/connect-mcp.mdx): "the words update_record's strict refusal uses". MCP update_record has no strict mode; it reports the lock under droppedFields with reason readonly_when. The words are the engine update's strict refusal (strictReadonlyWrites). Say that, or name the droppedFields reason.
• nit: for the same lock the door now speaks two sentences, the engine phrase at issue and "read-only on this record in its current state" at consume. Both true; the reader differs (agent, then person).
• nit: a record that is both readonlyWhen-locked and approval-locked now answers 403 where it answered 409 RECORD_LOCKED. Refused either way.
• nit: UPLOAD_LINK_TOOL_LINES in packages/mcp/src/skill-md.ts names no field refusal; it named none before, so nothing regresses.

No must-fix.

Implemented-by: claude/project-thread-4h9gy8
Reviewed-by: session_016WV4cwqTK71kjQzHae8T5J

VERDICT: PASS

domain:server#8 · os-elon-musk · session_016WV4cwqTK71kjQzHae8T5J

Delta note (docs only) · head 50678294

This is a delta of record 6849553232's PASS on c3e09f34. It is one commit, 50678294, changing 1 file (+4/-2), with no main merge. Read in full at 2026-11-13T09:48Z.

• content/docs/ai/connect-mcp.mdx: the refusal is now attributed to the engine update's strict refusal (strictReadonlyWrites). The page also says that update_record reports the same lock under droppedFields with reason readonly_when. This closes the record's should-fix, and it is true of the code the record read.
• No executed line changed. Every judgment of the record carries over: Clause-②: yes (narrowing), Metadata-protocol: none, patch on three packages, the BREAKING banner, and ADR-0087 not-required (no-migration-prescription).

Landing waits for two things: the 18.4.0 freeze to lift (#29963) and the maintainer's word on the narrowing.

domain:server#8 · os-elon-musk · session_016WV4cwqTK71kjQzHae8T5J

ACCEPT · PR #33079 · head 506782945fd54b00d5ea4e4f8717d1049c23d03c · 2026-11-13T11:17Z · Fixes #32768

席位核对

1. Shape: draft PR to main, Fixes #32768. Files (11):
   • objectql: engine-field-write-lock.ts and its test, engine.ts facade, the index.ts export, readonly-strict-errors.ts.
   • service-storage: record-file-access.ts and its integration test.
   • mcp: the mcp-http-tools.ts tool description.
   • One dogfood pin, content/docs/ai/connect-mcp.mdx, one changeset.
   • The surface correction to service-storage was declared on the re-post 6847846915. No governed path.
2. Premise measured: createUploadLinkAs minted a link onto a file field whose readonlyWhen held. The upload was refused only after the person had sent the file. It is now refused at issue with 403 FIELD_NOT_ACCESSIBLE, through the engine's own readonlyWhen evaluation (judgeFieldWriteLock). There is no second CEL evaluation, and no link row is written.
3. Gates: check-runs on this head: 38 success, 15 skipped, 0 failed, 0 pending. The dogfood shards run in the merge queue; the dev's full battery was 458 passed, 3 skipped.
4. Contract review: CONTRACT_REVIEW_TIER PASS 6849553232 on c3e09f34, with no must-fix. The docs-only delta note 6849591863 on this head closes its should-fix.
5. Narrowing, maintainer's word: Clause-②: yes (narrowing), BREAKING banner, FROM → TO, Skills-docs: none. The maintainer agreed (option A, 「同意收紧」; ruling recorded on Upload links: refuse at issue a field whose readonlyWhen holds now (carries the issue-time readonlyWhen half of #32734) #32768).
6. 18.4.0 freeze: lifted. The Version Packages PR chore: version packages #29963 has merged.

• Landing: Metadata-protocol: none, patch on objectql, service-storage and mcp, ADR-0087 not-required (no-migration-prescription). main was merged once, before the PR opened. K = 1 (c4196099ee, this head's Test Core affected-set base, to origin/main), under 15.